=head1 NAME

spm-tools - Source Package Manager Tools

=head1 SYNOPSIS

	spm-tools [-h] [--debug] [--version]
                 {dist,check,clean,lint,sane,merge,edit,which,pack,pkg,serve,disowned,upload}

=head1 DESCRIPTION

Source Package Manager Tools (SPMT) packs additional utilities to assist in the
system maintenance.

With the tools you can distribute tarballs of port(s) and share them with
friends so that other can benefit from your work. Along with the tarballs
sources, such as patches and archives, can be optionally fetched and packed in
the tarball.

Runtime dependencies of binaries, libraries and scripts can be checked to ensure
the system consistency which is useful, for an example, when cross-compiling or
when targets where force removed from the system.

Software that is not required by other software installed on the system can be
checked via clean mode.

Checking for various system issues such as cross-filesystem udev rules and
symbolic links can be perfomed. Also ports sanity can be checked for missing
maintainer, /dev/null output recirections (which is bad and hides problems when
they occure) and more.

Sanity checking SRCBUILDs for missing essential variables and general mistakes
can be done via sane mode.

Dealing with files backed up by SPM can be done in merge mode, interactively.

Editing SRCBUILD files can easily be done without knowing the exact path in the
repositories directory, the editor is picked from the EDITOR environmental
variable with fallback to Vim.

Getting full paths to targets is possible via which mode, all matches of the
pattern specified will be printed which can also be useful to check for
dublicate ports. In addition, the content of the SRCBUILD can be printed.

Software with SPM can be re-packed via pack mode, it depends on the footprint
and will bail out if file does not exist.

Package files from Arch Linux can be obtained via pkg mode, later they can be
converted (with some degree of success) to SRCBUILD via pkg2src.

Serving local caches (that includes repositories, sources and taballs) to the
local area netwrok can be done via serve mode. Do note that the functionality
is very basic and you may want to use dedicated application for this purpose.

System files not tracked by SPM can be checked for via disowned mode. By
default the scanning process does not perform cross-filesystem operations
which depending on your setup may not be desired, for an example if you
have /usr on a separate partition. The operation is usually slow.

Binary tarballs can be uploaded via FTP/FTPS to mirrors via upload mode.

=head1 OPTIONS

=head2 MAIN

positional arguments:
  {dist,check,clean,lint,sane,merge,edit,which,pack,pkg,serve,disowned}

optional arguments:
  -h, --help            Show this help message and exit
  --debug               Enable debug messages
  --version             Show SPM Tools version and exits

=head2 DIST MODE

positional arguments:
  TARGETS               Targets to apply actions on

optional arguments:
  -h, --help            Show this help message and exit
  -s, --sources         Include all sources in the archive
  -c, --clean           Clean all sources after creating archive
  -d DIRECTORY, --directory DIRECTORY
                        Set output directory

=head2 CHECK MODE

positional arguments:
  TARGETS               Targets to apply actions on

optional arguments:
  -h, --help            Show this help message and exit
  -f, --fast            Skip some files/links
  -a, --adjust          Adjust target depends
  -D, --depends         Check dependencies of target
  -R, --reverse         Check reverse dependencies of target

=head2 CLEAN MODE

optional arguments:
  -h, --help            Show this help message and exit

=head2 LINT MODE

positional arguments:
  TARGETS               Targets to apply actions on

optional arguments:
  -h, --help            Show this help message and exit
  -m, --man             Check for missing manual page(s)
  -u, --udev            Check for cross-filesystem udev rule(s)
  -s, --symlink         Check for cross-filesystem symlink(s)
  -d, --doc             Check for documentation
  -M, --module          Check for module(s) in non-standard directory
  -f, --footprint       Check for footprint consistency
  -b, --builddir        Check for build directory trace(s)
  -o, --ownership       Check ownership
  -e, --executable      Check for non-executable(s) in PATH
  -p, --path            Check for overlapping executable(s) in PATH
  -n, --shebang         Check for incorrect shebang of scripts
  -k, --backup          Check for incorrect or incomplete backup of files
  -c, --conflicts       Check for conflicts between targets
  -D, --debug           Check for missing debug symbols
  -a, --all             Perform all checks

=head2 SANE MODE

positional arguments:
  TARGETS               Targets to apply actions on

optional arguments:
  -h, --help            Show this help message and exit
  -e, --enable          Check for explicit --enable argument(s)
  -d, --disable         Check for explicit --disable argument(s)
  -n, --null            Check for /dev/null output redirection(s)
  -m, --maintainer      Check for missing maintainer
  -N, --note            Check for FIXME/TODO note(s)
  -v, --variables       Check for essential variables
  -t, --triggers        Check for unnecessary triggers invocation(s)
  -u, --users           Check for user(s) being added but not deleted
  -g, --groups          Check for group(s) being added but not deleted
  -s, --signatures      Check for signature(s) not in the sources array
  -a, --all             Perform all checks

=head2 MERGE MODE

optional arguments:
  -h, --help            Show this help message and exit

=head2 EDIT MODE

positional arguments:
  TARGETS               Targets to apply actions on

optional arguments:
  -h, --help            Show this help message and exit

=head2 WHICH MODE

positional arguments:
  PATTERN               Pattern to search for in remote targets

optional arguments:
  -h, --help            Show this help message and exit
  -c, --cat             Display content of SRCBUILD
  -p, --plain           Print in plain format

=head2 PACK MODE

positional arguments:
  TARGETS               Targets to apply actions on

optional arguments:
  -h, --help            Show this help message and exit
  -d DIRECTORY, --directory DIRECTORY
                        Set output directory

=head2 PKG MODE

positional arguments:
  TARGETS               Targets to apply actions on

optional arguments:
  -h, --help            Show this help message and exit
  -d DIRECTORY, --directory DIRECTORY
                        Set output directory

=head2 SERVE MODE

optional arguments:
  -h, --help            Show this help message and exit
  -p PORT, --port PORT  Use port for the server
  -a ADDRESS, --address ADDRESS
                        Use address for the server

=head2 DISOWNED MODE

optional arguments:
  -h, --help            Show this help message and exit
  -d DIRECTORY, --directory DIRECTORY
                        Set lookup directory
  -c, --cross           Scan cross-filesystem
  -p, --plain           Print in plain format

=head2 UPLOAD MODE

positional arguments:
  TARGETS               Targets to apply actions on

optional arguments:
  -h, --help            Show this help message and exit
  -H HOST, --host HOST  Set host
  -u USER, --user USER  Set user
  -d DIRECTORY, --directory DIRECTORY
                        Set upload directory
  -i, --insecure        Use insecure connection

=head1 EXAMPLES

Create a tarball of all sources, SRCBUILD, patches, etc. of grub and put the
tarball in the current directory:

    sudo spm-tools dist -sc -d=. grub

Run check of runtime dependencies of python, excluding various non-important
files such as headers, and correct them if necessary:

    sudo spm-tools check -faD python

Check for unneeded local targets, in other words - targets that are not required
by other local target:

    spm-tools clean

Run check for possible "bad things" on all local targets to ensure that the
system is in good condition, e.g. no cross-filesystem symlinks which can be
troublesome with a separate /usr partition:

    spm-tools lint -a $(spm local -pn ^)

Run check for possible "bad things" on all remote targets to ensure that the
ports are in good condition, e.g. there are at least 2-variables defined
(version and description):

    spm-tools sane -a $(spm remote -pn ^)

Merge all files backed up by SPM with the original ones:

    sudo spm-tools merge

Edit the glibc SRCBUILD, e.g. to apply some custom configure parameters:

    sudo spm-tools edit glibc

Print full path to vim target:

    spm-tools which -p vim

Backup gcc filese into tarball:

    spm-tools pack gcc

=head1 EXIT STATUS

SPM returns 0 on success and other on failure.
	
=head2 Unexpected error (1)

This is a general error. Triggered, most likely, by something that SPM is
not able to handle.

=head2 Internal error (2)

This error raises when a dependency, library, or other important thing
is missing or failed.

=head2 CONFIGPARSER (3)

This error raises when, at runtime, the module responsible for parsing the
configuration files fails badly. Its job usually is to parse the main,
repositories and mirrors configuration files.

=head2 SUBPROCESS (4)

This error raises when a subprocess, such as Git or Bash, failed to
execute a sub-command.

=head2 URLLIB (5)

This error raises when, at the prepare stage, the module responsible for
fetching files hits a wall. This can be '404 Not Found' or
'500 Internal Server Error'. For more info visit
http://en.wikipedia.org/wiki/List_of_HTTP_status_codes.

=head2 TARFILE (6)

This error raises when, at the prepare or merge stage, the module
responsible for compressing and decompressing Tar archives fails badly.

=head2 ZIPFILE (7)

This error raises when, at the prepare stage, the module responsible
for compressing and decompressing Zip archives fails badly.

=head2 SHUTIL (8)

This error raises when the module responsible for shell or system
operations fails badly. Its job usually is to copy or remove files and
directories.

=head2 OS (9)

This error raises when the module responsible for system files and
directories information gathering fails badly. Its job usually is to
check if X is file, symbolic link or directory.

=head2 IO (10)

This error raises when there is something wrong with the file/directory
permissions.

=head2 REGEXP (11)

This error raises when the module responsible for regular expressions
matching fails badly. If in doubt you should check the Python Re module
reference at http://docs.python.org/2/library/re.html.

=head2 FTPLIB (12)

This error raises when the FTP modules responsible for uploading files errors
out.

=head2 Interupt signal received (13)

This error raises when the user triggers keyboard interrupt via Ctrl+C key
combination.

=head1 BUGS

=head2 PYTHON MODULES

HTTPS requests do not do any verification of the server's certificate. For more
info visit http://docs.python.org/2/library/urllib2.html. Note that this
affects only Python versions older than 2.7.9.

There are three tar formats that are supported by the tarfile module. For more
info visit http://docs.python.org/2/library/tarfile.html#supported-tar-formats.
Note that the Zip and XZ formats are supported by SPM, the later via subprocess
calling `tar` or `bsdtar` directly.

=head2 SPM

Single quote inside double quoted text (and vice-versa) in the SRCBUILD
variables break the parser.

=head1 ENVIRONMENT

The following environment variables affect the execution of SPMT:

=head2 LANGUAGE, LC_ALL, LC_MESSAGES, and LANG

Used to specify locales to be used in the messages output.

=head2 EDITOR

Used to specify text-editor to be used when mering configuration files.

=head1 AUTHORS

Ivailo Monev (a.k.a. SmiL3y) <xakepa10@gmail.com>

Copyright (c) 2013-2015 Ivailo Monev licensed through custom license, see the
COPYING file bundled with the source code.

=head1 SEE ALSO

spm(8) SRCBUILD(5) scanelf(1) tar(1) bsdtar(1) xz(1) vim(1) locale(7)
